home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu143.dms / pu143.adf / setkey.doc / setkey.doc
Text File  |  1997-10-19  |  15KB  |  306 lines
  1. To Whom It may Concern:
  2.  
  3.    I Charles J. Carter am putting SetKey, which was formerly a commercial
  4. product, into the public domain due to a lot of reasons.  Some of which are
  5. the following:
  6.  
  7. 1) Very small number of sales (mainly due to lack of advertising). ie < 50
  8.    in over a year.
  9. 2) Since this utility works at the OS level it counts on the OS to work
  10.    consistently.  This software (OS) is not well documented and changes as
  11.    the OS is upgraded and as the hardware is upgraded.  I am NOT privy to
  12.    these changes in a timely manner, if at all, making it impossible to keep
  13.    the product current.
  14. 3) This utility SHOULD have been included with 1.2 and should be a part of
  15.    the OS as is the icon editor, font editor, etc...
  16. 4) And lastly my desire to do games programs.
  17.  
  18. One the plus side, since SetKey was released in FEB 87 there has only been
  19. one error found and that was caused by the console device not acting as
  20. advertised.  SetKey V2.0 works around this problem.
  21.  
  22. If anybody is interested all that is needed to upgrade this program for
  23. the A500 and A2000 is to add the extra keys for the keypad.  I've been
  24. told if you can live without these keys the program works just fine.
  25.  
  26. If you have any questions or comments email me on Plink. CJCarter ;8^)
  27.  
  28.      Warning:  There is a bug in SetKey that will cause a guru if you have
  29. any fast ram (anything more than 512K) in your Amiga and select "Load a
  30. Keymap from the Disk" from the menu.  You can edit the keymap that is
  31. currently in use when you start up SetKey, but if you want to load another
  32. keymap from disk to edit, turn off your fast ram first or you'll see the
  33. guru.  This bug does not affect your later use of the altered keymap at all,
  34. it is just a bug with this one menu item.  After exiting SetKey you can turn
  35. your fast ram back on.
  36.  
  37. PROGRAM DISCLAIMER: The program is provided "AS IS" without warranty of any
  38. kind, either expressed or implied, including, but not limited to, the 
  39. implied warranties of merchantability and fitness for a particular purpose.
  40. The entire risk as to the results and performance of the program is assumed
  41. by you.  Should the program prove defective, you assume the entire cost of all
  42. necessary servicing, repair or correction.
  43.  
  44.  
  45.  
  46.                                     SetKey
  47.  
  48.    The new command SetMap (V1.2) allows the use of different keyboards or the
  49. total reconfiguration of a keyboard!  Alas, the only keymaps available are
  50. for foreign keyboards or the Dvorak keyboard.  Wouldn't it be nice if you
  51. could reconfigure a keyboard to suit you needs?  SetKey allows you to do just
  52. that and a whole lot more.  SetKey is a keymap editor that allows up to eight
  53. strings to be assigned to most keys on the keyboard.  Also characters can be
  54. entered in HEX so that maximum flexibility is maintained.  The SetKey keymap
  55. editor is easy to use, easy to learn and best of all compatible with SetMap.
  56.  
  57.    SetKey can be used from WorkBench or the CLI.  If SetKey is run from the
  58. CLI, a keymap that is stored in DEVS:keymaps/ can be used as an argument.  If
  59. no keymap is specified then the current default keymap is used.  When SetKey
  60. is run, it presents the user with a diagram of the keyboard with all the keys
  61. ready to be edited.  Using SetKey starts with selecting a qualifier, if any,
  62. then a key to edit.
  63.  
  64.   For anyone unfamiliar with the concept of qualifiers, there are three
  65. qualifiers on the Amiga keyboard, shift, alt, and control.  Any time that you
  66. hold one of the qualifier keys and press another key, the code which is sent
  67. to the computer includes the qualifier.  This code is then translated by
  68. looking up (in the keymap!) the code and qualifier, and the translated code
  69. is finally sent to the application as a character or a string of characters. 
  70. Since there is no restriction placed on the characters in the keymap, keys
  71. may "map" to strings containing carriage returns or other control codes, so
  72. that a single keypress can be made to perform several commands.  In addition,
  73. qualifiers may be combined (e.g. shift+alt or shift+alt+control) making a
  74. total of eight different strings for each key.  SetKey supports the mapping
  75. of all eight combinations with either characters or strings.  Now that we
  76. have explained what SetKey does, lets examine how it works.
  77.  
  78.    To get familiar with SetKey, run the program from either CLI or WorkBench.
  79. First press the letter "a".  Notice the a key on the keyboard picture is
  80. highlighted, and a box appears at the bottom of the screen with quite a bit
  81. of information in it.  At the top of this box are three fields, indicating
  82. the key selected, its internal code value in hexidecimal, and any qualifiers
  83. currently selected.  Note that the current display shows "none" for the
  84. qualifiers, since we did not press any qualifier keys before we pressed the
  85. "a" key.  To indicate a qualifier, simply press the desired qualifier(s)
  86. BEFORE selecting the key you intend to edit.  This action will highlight the
  87. qualifier(s) you select, and when you subsequently press a key to edit, you
  88. will see the qualifiers in the third field of the first line in the box.  In
  89. the center of the box is a long string gadget containing the letter "a". 
  90. There is a short string gadget in the bottom left corner, used for entering
  91. characters in hex.  There are two more gadgets in the box, the "Modify
  92. Keymap" gadget and the "Cancel" gadget.  Use the mouse to point at the Cancel
  93. gadget and press the select mouse button.  The box will disappear and the a
  94. key will return to normal on the display.  Now lets actually map a string to
  95. the shifted f1 key and test it in the CLI.
  96.  
  97.    First press any shift key on the keyboard (you may point at the keys in
  98. the display and press the select button on the mouse if you prefer).  All the
  99. shift keys on the keyboard should be highlighted.  Now press the f1 key (or
  100. point and click).  The box will reappear at the bottom of the display with 4
  101. characters in the long string gadget in the center of the box.  The 4
  102. characters should be an escape character (which Intuition displays in string
  103. gadgets as a tall box shaped character) then "10~".  We are going to replace
  104. this relatively useless string with one that actually does something.  First
  105. click in the long string gadget to activate it.  The cursor will be displayed
  106. inside the gadget.  Delete all the characters in the box and then type  "cd
  107. df0:" without the quotation marks.  Now we would like to set up our new
  108. shifted f1 to perform the cd df0: without having to press return after we
  109. press shift f1.  To do this, we need to include the "return" at the end of
  110. our string.  But pressing return now causes the display to blink and include
  111. a return in the string with the cursor placed one character to the right
  112. ready for more input.
  113.  
  114.   The hex entry gadget allows you to type in a hex number, which is
  115. translated into a character and placed in the string at the current cursor
  116. position, replacing whatever was previously there.  Start by getting the
  117. cursor to the end of the long string gadget.  Now point at the hex gadget and
  118. press the select button.  The value displayed to the right of the hex gadget
  119. should change to 00.  This is the value in hex of the character at the end of
  120. the string in the long string gadget.  Type whatever HEX value you want, if
  121. any, at the current cursor location and hit return.  Then click back on the
  122. string input gadget to continue input.  Notice that a tall box appears at the
  123. end of the long string gadget.  SetKey has replaced the 00 with the HEX value
  124. you have entered.  Now that we have finished modifying the key, let's store 
  125. it in the temporary working keymap by clicking on the Modify Keymap gadget.
  126.  
  127.   You may repeat this process for other keys on the display until you have
  128. the keys "mapped" according to your own preferences.  The new keymap may now
  129. be saved by pulling down the Main Control menu and selecting "Save a keymap
  130. to the disk".  When you do this, another box will be displayed with a
  131. directory string gadget and a filename string gadget in it.  The directory
  132. string gadget points to DEVS:keymaps by default.  This is the directory that
  133. setmap will look in later when we activate our keymap, so it is best to put
  134. all of your new keymaps here.  Type in "example" in the filename gadget and
  135. click on the Save gadget.  If your DEVS:keymaps disk has room and isn't write
  136. protected, the file will be stored.  To exit, you may either click on the
  137. closewindow gadget or use one of the exit options from the main menu.  Now
  138. we're ready to activate the new keymap.  From the CLI, enter "setmap
  139. example".  Your keymap has now been activated.  To see it work, hold shift
  140. and press f1.  The CLI should do cd df0: for you.  Try out any other keys you
  141. have mapped.  That's all there is to it.  You are free to make further
  142. modifications by using SetKey again, but be aware that setmap will not
  143. replace a keymap which has already been activated.  If you make changes with
  144. SetKey and store under the same name, setmap will simply reactivate your
  145. first version of the keymap.  The only way to activate a new version with the
  146. same name is to reboot the Amiga and then do setmap again.
  147.  
  148.  
  149. The CopyKeys keymap, using the ARROW keys, provides a convenient way to run
  150. the Copy, DiskCopy, and Format commands.  
  151.  
  152. USE ARROW KEYS AS FOLLOWS: 
  153.  
  154. ALT + Lft Arrow        -  Sets up ramdisc by placing the Copy,
  155.                   DiskCopy, and Format commands in ram:
  156.  
  157. ALT + Up Arrow         -  Formats a disk in drive df1:
  158.  
  159. ALT + Rt Arrow         -  Copies all files from df0: to previously 
  160.                           formatted disk in Df1:
  161.  
  162. ALT + Down Arrow       -  DiskCopy from d0: to df1:
  163.  
  164. ALT/Shift + Lft Arrow  -  Used to delete all files in ramdisc.
  165.  
  166.  
  167.  
  168.  
  169. ----------------------------------------------------------------------
  170.  
  171. The CopyKeys keymap, using the HELP key, provides a convienient way to
  172. utilize commands related to SetKey and the keymaps.
  173.  
  174. USE THE HELP KEY AS FOLLOWS:
  175.  
  176. Help                   -  Reads this help file.
  177.  
  178. Shift + Help           -  ShowKey command lists current keymap settings.
  179.  
  180. ALT + Help           -  SetMap command allows user to change to another
  181.                           keymap.
  182.  
  183. ALT/Shift + Help       -  Runs SetKey utility.
  184.  
  185.  
  186. The EdKeys keymap, using the ARROW keys, provides a convenient way to run Ed.
  187.  
  188. USE KEYS AS FOLLOWS:
  189.  
  190. SHIFT + Lft Arrow        -  Begin/End of line.
  191.  
  192. SHIFT + Up Arrow         -  Up a Screen.
  193.  
  194. SHIFT + Rt Arrow         -  Begin/End of line.
  195.  
  196. SHIFT + Down Arrow       -  Down a Screen.
  197. ----------------------------------------------------------------------
  198.  
  199. ALT + Lft Arrow        -  Word Forward.
  200.  
  201. ALT + Up Arrow         -  Top of File.
  202.  
  203. ALT + Rt Arrow         -  Word Backward. 
  204.  
  205. ALT + Down Arrow       -  Bottom of File.
  206. ----------------------------------------------------------------------
  207.  
  208. The EdKeys keymap can also provide macro capability to standard Ed.
  209.  
  210. Help                   -  Open New Line.
  211.  
  212. Enter                  -  Autoindent (Macro for use with standard Ed).
  213.  
  214. F1                     -  Quit.
  215.  
  216. SHIFT + F1             -  Save and Exit.
  217.  
  218.  
  219. This is just a start of all of the Possiblities of SetKey.
  220.  
  221.                               SetKey.Notes
  222.  
  223. See the file SetKey.Tutorial for a complete description of how to use SetKey.
  224.  
  225. SetKey Main Control Menu options:
  226.  
  227.    Select View or Change mode:
  228.       In "View" mode setkey simply displays the current mapping of any key
  229.       which is selected. "Change" mode allows you to change the mapping of
  230.       the keys.
  231.  
  232.    Load a keymap from the disk:
  233.       Loads a keymap for editing.
  234.  
  235.    Save a keymap to the disk:
  236.       Saves your current changes.
  237.  
  238.    End keymap editing:
  239.       You may exit and execute setmap to set your work as the active keymap
  240.       or exit without setting this map by choosing one of the suboptions.
  241.  
  242. ----------------------------------------------------------------------------
  243.  
  244.    Showkey:
  245.  
  246.    Showkey is a very simple utility which examines all the keys in the
  247. current default keymap and prints a paginated listing of the keys which have
  248. non-escape strings mapped to them.  This can be quite helpful if you have
  249. trouble remembering how you mapped the keyboard.  This version will detect
  250. keymaps that have keys with strings that are too long (ie > 127).
  251.  
  252. ----------------------------------------------------------------------------
  253.  
  254.    Tech Notes:
  255.  
  256.    Each string mapped to a key may contain up to 127 characters.  The total
  257. for any key (all qualifiers) must be less than 256.  This is not really a
  258. handicap in actual operation, it's just implicit in the way the C=A keymap
  259. structure is designed.
  260.    Dead keys are NOT supported by SetKey.  What ARE dead keys??  We had a
  261. hard time figuring it out too.  Suffice to say, they are unnecessary, but if
  262. you really need them, there's always the usa keymap.
  263.    Sometimes when you change back & forth between the hex gadget and the
  264. string gadget you'll notice the cursor will disappear.  Intuition seems to
  265. toggle the cursor status whenever RefreshGadgets is called, causing the
  266. cursor to disappear.  If you begin typing into the gadget, though, the cursor
  267. will reappear and remain until you deselect the gadget.
  268.    Setmap runs down the keymap resource list (in RAM) to see if a copy of the
  269. keymap you have requested is already loaded.  If it finds a match, it simply
  270. sets it as the current keymap for the task which called it.  This is good and
  271. bad.  It's good in that it saves time if he can find it in RAM. It's bad
  272. because there is no way to replace a keymap once it has been added to the
  273. resource list (at least not safely, because deleting it from the resource
  274. list without knowing whether or not it is being used at present by another
  275. task could be disastrous).  But that's the way it works.
  276.    Needless to say by now, SetKey ONLY works with V1.2 of AmigaDos!
  277.  
  278. The ZorkKeys keymap is setup to make playing adventure games easy and fun.
  279.  
  280. /********** Current Key Assignments **********/
  281.  Key       : Qual  :  String  :  Comment
  282. -----------------------------------------------
  283. keypad 0   : none  : d<CR>    :  Down
  284. keypad 1   : none  : sw<CR>   :  SouthWest
  285. keypad 2   : none  : s<CR>    :  South
  286. keypad 3   : none  : se<CR>   :  SouthEast
  287. keypad 4   : none  : w<CR>    :  West
  288. keypad 5   : none  : u<CR>    :  Up
  289. keypad 6   : none  : e<CR>    :  East
  290. keypad 7   : none  : nw<CR>   :  NorthWest
  291. keypad 8   : none  : n<CR>    :  North
  292. keypad 9   : none  : ne<CR>   :  NorthEast
  293.  
  294. up arrow   : none  : n<CR>    :  North
  295. down arrow : none  : s<CR>    :  South
  296. rt arrow   : none  : e<CR>    :  East
  297. lft arrow  : none  : w<CR>    :  West
  298.  
  299.  
  300. f1         : none  : again<CR>:  Repeat last command
  301. f2         : none  : wait<CR> :  Wait
  302. f3         : none  : save<CR> :  Save
  303. f4         : none  : restore<CR> Restore
  304.  
  305. This keymap can be tailored to your current game with SetKey.
  306.